Next: , Previous: Alternative Buses, Up: Top

9 Errors and events.

The internal actions can be traced by running in a debug mode.

— Variable: dbus-debug

If this variable is non-nil, D-Bus specific debug messages are raised.

Input parameters of dbus-call-method, dbus-call-method-non-blocking, dbus-call-method-asynchronously, and dbus-register-signal are checked for correct D-Bus types. If there is a type mismatch, the Lisp error wrong-type-argument D-Bus ARG is raised.

All errors raised by D-Bus are signaled with the error symbol dbus-error. If possible, error messages from D-Bus are appended to the dbus-error.

— Special Form: dbus-ignore-errors forms...

This executes forms exactly like a progn, except that dbus-error errors are ignored during the forms. These errors can be made visible when dbus-debug is set to t.

Incoming D-Bus messages are handled as Emacs events, see see Misc Events. They are retrieved only, when Emacs runs in interactive mode. The generated event has this form:

     (dbus-event bus type serial service path interface member handler
             &rest args)

bus identifies the D-Bus the message is coming from. It is either the symbol :system or the symbol :session.

type is the D-Bus message type which has caused the event. It can be dbus-message-type-invalid, dbus-message-type-method-call, dbus-message-type-method-return, dbus-message-type-error, or dbus-message-type-signal. serial is the serial number of the received D-Bus message.

service and path are the unique name and the object path of the D-Bus object emitting the message. interface and member denote the message which has been sent.

handler is the callback function which has been registered for this message (see see Signals). When a dbus-event event arrives, handler is called with args as arguments.

In order to inspect the dbus-event data, you could extend the definition of the callback function in Signals:

     (defun my-dbus-signal-handler (&rest args)
       (message "my-dbus-signal-handler: %S" last-input-event))

There exist convenience functions which could be called inside a callback function in order to retrieve the information from the event.

— Function: dbus-event-bus-name event

Returns the bus name event is coming from. The result is either the symbol :system or the symbol :session.

— Function: dbus-event-message-type event

Returns the message type of the corresponding D-Bus message. The result is a natural number.

— Function: dbus-event-serial-number event

Returns the serial number of the corresponding D-Bus message. The result is a natural number.

— Function: dbus-event-service-name event

Returns the unique name of the D-Bus object event is coming from.

— Function: dbus-event-path-name event

Returns the object path of the D-Bus object event is coming from.

— Function: dbus-event-interface-name event

Returns the interface name of the D-Bus object event is coming from.

— Function: dbus-event-member-name event

Returns the member name of the D-Bus object event is coming from. It is either a signal name or a method name.

D-Bus errors are not propagated during event handling, because it is usually not desired. D-Bus errors in events can be made visible by setting the variable dbus-debug to t. They can also be handled by a hook function.

— Variable: dbus-event-error-hooks

This hook variable keeps a list of functions, which are called when a D-Bus error happens in the event handler. Every function must accept two arguments, the event and the error variable catched in condition-case by dbus-error.

Such functions can be used the adapt the error signal to be raised. Example:

          (defun my-dbus-event-error-handler (event error)
            (when (string-equal (concat dbus-service-emacs ".FileManager")
                                (dbus-event-interface-name event))
              (message "my-dbus-event-error-handler: %S %S" event error)
              (signal 'file-error (cdr error))))

          (add-hook 'dbus-event-error-hooks 'my-dbus-event-error-handler)

Hook functions shall take into account, that there might be other D-Bus applications running. Therefore, they shall check carefully, whether a given D-Bus error is related to them.